Organize host and robot streaming releases

robot/ros2/OmniSocketGo_robot_ros/docs/ROS2_CAMERA_FORWARDING.md

@@ -0,0 +1,117 @@
+# ROS 2 相机转发说明
+
+## 设计
+
+```text
+Orbbec 驱动 / proc_manager
+        │ ROS 2 Image topic
+        ▼
+omnisocket_camera_bridge
+        │ /dev/shm/omnisocket-rgb-{head,waist}
+        ▼
+b_side_omnid（OmniSocketGo 视频编码与 KCP 发送）
+        │ 原有视频包协议
+        ▼
+远端 OmniSocketGo/robot-command-center
+```
+
+设备只由驱动节点打开。ROS 2 桥接节点订阅 `sensor_msgs/msg/Image`，每路仅保留一帧最新图像写入共享内存；C 端读取共享内存后继续使用原有缩放、MJPEG 编码和网络发送逻辑。因此切换摄像头不会再次打开或关闭 `/dev/video*`。
+
+## 首次构建
+
+在机器人上：
+
+```bash
+sudo apt-get install python3-colcon-common-extensions \
+  ros-jazzy-rclpy ros-jazzy-sensor-msgs
+
+cd ~/OmniSocketGo_robot_ros/ros2
+source /opt/ros/jazzy/setup.bash
+colcon build
+source install/setup.bash
+
+cd ~/OmniSocketGo_robot_ros
+make b_side_omnid
+```
+
+如果环境不是 Jazzy，把 `/opt/ros/jazzy` 换成实际 ROS 2 发行版目录。
+
+## 启动
+
+推荐使用项目启动脚本。它会：
+
+1. 检查 `proc_manager.service`；
+2. `proc_manager` 已运行且已经提供 RGB topic 时，只等待并复用这些 topic；
+3. `proc_manager` 已运行但没有占用头/腰设备时，按配置启动 `orbbec_head.service` 和 `orbbec_waist.service`；如果设备已被占用则拒绝重复启动；
+4. `proc_manager` 未运行时，同样按配置启动两个相机服务，再等待 topic；
+5. 启动 ROS 2 RGB 桥；
+6. 启动 `b_side_omnid`。
+
+```bash
+cd ~/OmniSocketGo_robot_ros
+source scripts/dev/load-env.sh
+source scripts/dev/robot-remote.env
+source scripts/dev/robot-remote.env.local  # 如有本机覆盖
+scripts/dev/start-b-side-omnid.sh
+```
+
+默认变量：
+
+```bash
+OMNI_CAMERA_SOURCE=ros2
+OMNI_CAMERA_ACTIVE=head       # head 或 waist
+OMNI_PROC_MANAGER_AUTO_START=0
+OMNI_CAMERA_START_SERVICES=1
+OMNI_ROS2_BRIDGE_AUTO_START=1
+```
+
+`OMNI_PROC_MANAGER_AUTO_START=1` 可让脚本在服务未运行时尝试启动 `proc_manager`；需要 sudo 权限。脚本只在确认头部/腰部设备节点空闲时启动 `orbbec_head/waist.service`，不会停止现有服务或抢占已被占用的设备。
+
+## 单独启动桥接节点
+
+```bash
+source /opt/ros/jazzy/setup.bash
+source ~/OmniSocketGo_robot_ros/ros2/install/setup.bash
+ros2 run omnisocket_camera_bridge omnisocket_ros_camera_bridge \
+  --ros-args \
+  -p head_topic:=/ob_camera_head/color/image_raw \
+  -p waist_topic:=/ob_camera_waist/color/image_raw \
+  -p head_shm:=/dev/shm/omnisocket-rgb-head \
+  -p waist_shm:=/dev/shm/omnisocket-rgb-waist
+```
+
+先确认桥接节点有帧：
+
+```bash
+ros2 topic hz /ob_camera_head/color/image_raw
+ros2 topic hz /ob_camera_waist/color/image_raw
+ls -lh /dev/shm/omnisocket-rgb-head /dev/shm/omnisocket-rgb-waist
+```
+
+查看 `logs/runtime/b-side-omnid.status.json`，应看到 `video_input_source: ros2`、递增的
+`video_frames_sent`，以及当前的 `video_active_camera`。这可以确认 C
+视频管线正在读取 ROS2 桥接帧，而不是打开 `/dev/video*`。
+
+## 切换头部/腰部
+
+视频控制通道仍使用原有文本命令：
+
+```text
+camera:head
+camera:waist
+```
+
+两路 ROS 2 订阅线程持续运行，切换只改变 C 端读取和发送的共享内存槽，不会重新连接相机或触碰 `/dev/video*`。
+
+## 兼容旧 V4L2 模式
+
+仅在没有 ROS 2 图像 topic 的临时测试环境使用：
+
+```bash
+OMNI_CAMERA_SOURCE=v4l2 \
+OMNI_CAMERA_HEAD_DEVICE=/dev/video26 \
+OMNI_CAMERA_WAIST_DEVICE=/dev/video18 \
+scripts/dev/start-b-side-omnid.sh
+```
+
+ROS-native 项目默认不走这条路径。

robot/ros2/OmniSocketGo_robot_ros/docs/ROS_CAMERA_INTERFACES.md

@@ -0,0 +1,44 @@
+# ROS 2 相机接口（RGB + 深度）
+
+本项目的 ROS 2 相机输入来自 Orbbec 节点，不再直接打开 `/dev/video*`。头部和腰部相机分别发布下面的接口。
+
+## 头部相机
+
+| 数据 | Topic | 消息类型 |
+|---|---|---|
+| 彩色图像 | `/ob_camera_head/color/image_raw` | `sensor_msgs/msg/Image` |
+| 彩色内参 | `/ob_camera_head/color/camera_info` | `sensor_msgs/msg/CameraInfo` |
+| 彩色元数据 | `/ob_camera_head/color/metadata` | `orbbec_camera_msgs/msg/Metadata` |
+| 深度图像 | `/ob_camera_head/depth/image_raw` | `sensor_msgs/msg/Image` |
+| 深度内参 | `/ob_camera_head/depth/camera_info` | `sensor_msgs/msg/CameraInfo` |
+| 深度元数据 | `/ob_camera_head/depth/metadata` | `orbbec_camera_msgs/msg/Metadata` |
+| 深度到彩色变换 | `/ob_camera_head/depth_to_color` | 由 Orbbec 驱动发布 |
+
+## 腰部相机
+
+| 数据 | Topic | 消息类型 |
+|---|---|---|
+| 彩色图像 | `/ob_camera_waist/color/image_raw` | `sensor_msgs/msg/Image` |
+| 彩色内参 | `/ob_camera_waist/color/camera_info` | `sensor_msgs/msg/CameraInfo` |
+| 彩色元数据 | `/ob_camera_waist/color/metadata` | `orbbec_camera_msgs/msg/Metadata` |
+| 深度图像 | `/ob_camera_waist/depth/image_raw` | `sensor_msgs/msg/Image` |
+| 深度内参 | `/ob_camera_waist/depth/camera_info` | `sensor_msgs/msg/CameraInfo` |
+| 深度元数据 | `/ob_camera_waist/depth/metadata` | `orbbec_camera_msgs/msg/Metadata` |
+| 深度到彩色变换 | `/ob_camera_waist/depth_to_color` | 由 Orbbec 驱动发布 |
+
+默认 RGB 分辨率由相机驱动决定，常见为 `1280x720`、`rgb8`。实际值请以运行时消息为准：
+
+```bash
+ros2 topic echo /ob_camera_head/color/image_raw --once
+ros2 topic echo /ob_camera_head/depth/image_raw --once
+ros2 topic echo /ob_camera_head/color/camera_info --once
+```
+
+应用节点可以同时订阅 RGB、深度、CameraInfo 和元数据。RGB 转发桥只订阅彩色图像；深度和标定接口保留在 ROS 2 内，供本地感知、对齐和测距节点使用。不要把深度图像通过当前视频编码通道发送，除非另行设计深度压缩协议。
+
+## QoS 与同步建议
+
+- 图像订阅使用 `BEST_EFFORT`、队列深度 2，优先获取最新帧，避免实时转发被旧帧阻塞。
+- RGB 与深度需要配对时，应使用消息时间戳进行近似同步，而不是假设两个回调严格交错。
+- `depth_to_color` 和 `CameraInfo` 必须随相机配置一起使用；不能用另一台相机的内参替代。
+- `/dev/video*` 只由 Orbbec/`proc_manager` 负责，应用节点不再调用 V4L2 抢占设备。