ros_contorl/docs/ENVIRONMENT.md

环境安装（按本机快照复现）

本文是 2026-10-09 在这台工控机上核对过的软件栈，用来在另一台电脑上装出同一套能跑本仓库的环境。 核对来源：/etc/os-release、conda-meta/history、conda list、~/flexiv_install 的 cmake 版本文件、nvidia-smi。

日常怎么用已经装好的环境，看 QUICKSTART.md。本文只回答「从一台空的 Ubuntu 装到能 source scripts/env.sh」。

---

1. 本机现在是什么

项	本机实测
系统	Ubuntu 22.04.5 LTS，x86_64，内核 6.8.0-138-generic
GPU	NVIDIA GeForce RTX 3090 24GB，驱动 595.91.07（DKMS）。nvidia-smi 报告的 CUDA 是驱动上限 13.2
推理用的 CUDA	不装系统 CUDA toolkit。PyTorch / TensorRT 用 pip wheel 自带的 CUDA 12.4 用户态库
ROS	Humble。本机 没有 /opt/ros/humble，ROS 在 conda 里（RoboStack）
Conda	Anaconda3 装在 ~/anaconda3，conda 25.11.1
真机环境	conda 环境 ros_flexiv，Python 3.11.15，约 15GB
仿真环境	conda 环境 ros_gz_sim，Python 3.11.6，Gazebo Sim 6.16.0（Fortress / ign gazebo），约 5.1GB
工作区	仓库在 ~/ros2（ASCII）。~/文档/ros2 只是指向它的符号链接
Flexiv C++	~/flexiv_install，flexiv_rdk 1.9.1（spdlog 1.9.2，Boost 1.83.0），约 194MB
Flexiv Python	~/rdk_py310/bin/python → 系统 /usr/bin/python3.10（3.10.12）+ flexivrdk==1.9.1 + numpy==1.26.4
DDS 域	真机 ROS_DOMAIN_ID=0，仿真强制 77

真机和仿真是两套 conda、两套 colcon 产物，互不覆盖：

	真机	仿真
激活	source ~/ros2/scripts/env.sh	source ~/ros2/scripts/sim_env.sh
conda	ros_flexiv	ros_gz_sim
产物	build/ install/	build_sim/ install_sim/
域	0	77

同一只 shell 里来回 source 会残留 PATH / PYTHONPATH。换环境时开新终端。

---

2. 新机器先对齐的路径

下面这些路径被脚本写死为用户 cc 的家目录。新机器用同一个用户名 cc（家目录 /home/cc）时，后面的命令可以原样复制。

路径	谁在用
/home/cc/anaconda3	scripts/run_real.sh、scripts/run_mock_demo.sh 直接 source 这个 conda.sh。scripts/env.sh 用的是 $HOME/anaconda3，两边要是同一个目录
/home/cc/rdk_py310/bin/python	run_real.sh、test_rdk_python.sh、rdk_switch_tool.sh、scripts/lib/real_preflight.py 的默认 RDK_PYTHON
/home/cc/flexiv_install	run_real.sh 用 $HOME/flexiv_install（随用户走）
/home/cc/ros2	工作区。colcon build 必须在这条 ASCII 路径下，不要在中文目录里编

用户名不是 cc 时，至少要改 scripts/run_real.sh 里的 conda 路径，并在启动前 export RDK_PYTHON=$HOME/rdk_py310/bin/python。否则真机入口会去找 /home/cc。

建议磁盘空闲 40GB 以上（两个 conda 环境加下载缓存）。

---

3. 系统包与显卡

sudo apt update
sudo apt install -y \
  build-essential git curl wget \
  python3.10 python3-pip \
  v4l-utils usbutils \
  dkms linux-headers-$(uname -r)
sudo usermod -aG dialout "$USER"

dialout 给夹爪的 USB–RS485（/dev/ttyUSB*）。加完组要重新登录。

显卡驱动装到能让 nvidia-smi 跑起来即可。本机是 595.91.07。驱动只要够跑 CUDA 12.4（远低于 595 的驱动也可以），PyTorch 的 12.4 wheel 就能用。不要再装一套系统级 CUDA toolkit，避免和 wheel 里的 libcudart 抢。

Orisys 视触觉相机会被 USB 自动休眠卡死。本机规则文件是 /etc/udev/rules.d/99-orisys-uvc.rules：

# Orisys 视触觉相机 (1bcf:2281)：禁止 USB 自动休眠（autosuspend 会把 UVC 相机搞到内核态卡死）
ACTION=="add|bind", SUBSYSTEM=="usb", ATTR{idVendor}=="1bcf", ATTR{idProduct}=="2281", ATTR{power/control}="on", ATTR{power/autosuspend}="-1"

写好后 sudo udevadm control --reload-rules && sudo udevadm trigger。

---

4. Anaconda

装到 $HOME/anaconda3（安装器里选 Just Me、路径填这个）。不要装成 ~/miniconda3 或其他目录：run_real.sh 写死了 /home/cc/anaconda3/etc/profile.d/conda.sh。

本机 conda 版本是 25.11.1。装完新开一个终端：

source "$HOME/anaconda3/etc/profile.d/conda.sh"
conda --version

频道不要写进 ~/.condarc 当成全局默认。本机 ~/.condarc 只有 defaults，RoboStack 的频道是每次安装命令显式带上的：-c robostack-staging -c conda-forge。

---

5. 真机环境 ros_flexiv

下面三条 conda 命令来自本机 ~/anaconda3/envs/ros_flexiv/conda-meta/history（2026-08-21 创建，2026-08-25 装 ROS）。pip 那一段是按同日 conda list 里的 pypi 版本还原的；当初的 pip install 原文没有留在 conda 历史里。

source "$HOME/anaconda3/etc/profile.d/conda.sh"

conda create -n ros_flexiv python=3.11 pip -y

conda install -y -n ros_flexiv -c robostack-staging -c conda-forge \
  ros-humble-ros-base \
  ros-humble-robot-state-publisher \
  ros-humble-xacro \
  ros-humble-tf2-ros \
  ros-humble-joint-state-publisher \
  compilers cmake make pkg-config catkin_pkg empy lark-parser numpy \
  colcon-common-extensions

conda install -y -n ros_flexiv -c robostack-staging -c conda-forge \
  ros-humble-rviz2

conda install -y -n ros_flexiv -c robostack-staging -c conda-forge \
  ros-humble-moveit \
  ros-humble-moveit-configs-utils \
  ros-humble-control-msgs \
  ros-humble-controller-manager \
  ros-humble-joint-trajectory-controller \
  ros-humble-ros2-control \
  ros-humble-ros2-controllers

然后钉住本机正在用的 pip 包。Humble 的 rosidl 要 empy 3.x（conda 有时会给 4.x，构建消息包时会报 AttributeError: NoneType object has no attribute shutdown）。TensorRT 装 tensorrt-cu12，不要装元包 tensorrt。

conda activate ros_flexiv

python -m pip install \
  'empy==3.3.4' \
  'lark==1.3.1' \
  'numpy==2.4.6' \
  'opencv-python-headless==4.10.0.84' \
  'pyrealsense2==2.58.3.10794' \
  'pyserial==3.5' \
  'minimalmodbus==2.1.1' \
  'onnx==1.22.0' \
  'onnxruntime==1.30.0' \
  'onnxruntime-gpu==1.29.0' \
  'tensorrt-cu12==10.13.3.9' \
  'ultralytics==8.4.123'

python -m pip install \
  'torch==2.6.0+cu124' \
  'torchvision==0.21.0+cu124' \
  --index-url https://download.pytorch.org/whl/cu124

相机走 pyrealsense2，本机没有装 ros-humble-realsense2-camera。夹爪 Modbus 走 pyserial + minimalmodbus。

Orisys SDK 不在 git 里。把本机这个 wheel 拷过去再装（--no-deps，避免它改写上面的 torch / numpy）：

# 源文件：~/sensor_ws/0.4.2/orisys-0.4.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
conda activate ros_flexiv
python -m pip install --no-deps \
  "$HOME/sensor_ws/0.4.2/orisys-0.4.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl"

本机这个环境里还有 Jupyter、PySide6、flexiv-assembly 等包，本仓库脚本不用它们，新机器不必装。

激活后应看到：

conda activate ros_flexiv
python -c 'import sys; print(sys.version)'          # 3.11.x
echo "ROS_DISTRO=$ROS_DISTRO"                        # humble
python -c 'import rclpy, cv2, pyrealsense2, torch; import tensorrt as trt; print("torch", torch.__version__); print("tensorrt", trt.__version__); print("cuda", torch.cuda.is_available())'

本机对应输出：torch 2.6.0+cu124，tensorrt 10.13.3.9，torch.cuda.is_available() 为真。

---

6. Flexiv RDK（与 conda 分开）

运行中的库是 1.9.1。仓库里的 src/flexiv_rdk 工程版本是 2.1（project(flexiv_rdk VERSION 2.1 ...)）。scripts/build_flexiv_rdk.sh 编的是这份当前源码，产物和本机 ~/flexiv_install 不是同一个版本。

新机器要对齐正在跑的这套，把本机这两个目录原样拷过去：

# 在新机器上，从本机拉（把 user@old-host 换成这台工控机）
rsync -a user@old-host:~/flexiv_install/  ~/flexiv_install/
rsync -a user@old-host:~/rdk_py310/       ~/rdk_py310/

拷完核对：

grep 'set(PACKAGE_VERSION' ~/flexiv_install/lib/cmake/flexiv_rdk/flexiv_rdk-config-version.cmake
# 应有 set(PACKAGE_VERSION "1.9.1")

~/rdk_py310/bin/python -c 'import flexivrdk; print(flexivrdk.__version__)'
# 1.9.1

~/rdk_py310/bin/python 是一个壳：清掉 PYTHONHOME（避免 conda 污染），再用系统 Python 3.10 加上自己的 site-packages。flexivrdk 1.9.1 的 ABI 是 cp310，不要装进 ros_flexiv（那是 Python 3.11）。

壳脚本内容（拷目录时已经带上；若要手写，注意把路径改成新机器的家目录）：

#!/bin/bash
export PYTHONPATH="${HOME}/rdk_py310/lib/python3.10/site-packages${PYTHONPATH:+:$PYTHONPATH}"
unset PYTHONHOME
exec /usr/bin/python3.10 "$@"

---

7. 仿真环境 ros_gz_sim

用仓库脚本，可重复执行：

bash ~/ros2/scripts/install_sim_env.sh
bash ~/ros2/scripts/install_sim_env.sh --verify

脚本会创建 ros_gz_sim（Python 3.11），从 robostack-staging + conda-forge 安装 ros-humble-ros-base、ros-humble-ros-gz、ros-humble-gz-ros2-control、ros2_control / ros2_controllers、controller_manager、xacro、tf2_ros、camera-info-manager、image-transport-plugins，并把 empy 钉在 3.3.4。

本机 --verify 能通过时的关键版本：

包	版本
Gazebo Sim（ign gazebo --version）	6.16.0
libignition-gazebo6	6.16.0
ros-humble-ros-gz	0.244.20
ros-humble-gz-ros2-control	0.7.15
empy	3.3.4（conda-forge）
numpy	1.26.4（conda-forge）

Humble 配的是 Gazebo Fortress，命令是 ign gazebo，不是 gz sim。

仿真环境里没有真机那套 torch / tensorrt / pyrealsense2 / onnx。本机仿真环境额外有一个 pip 的 onnxruntime==1.30.0。缺 onnx 时部分单测会红，这是现况；不要把真机的 pip 依赖灌进 ros_gz_sim，两个环境是故意隔开的。

---

8. 工作区、现场配置、编译

git clone <本仓库> ~/ros2
cd ~/ros2
# 若习惯从中文路径进： ln -s ~/ros2 ~/文档/ros2

config/site.yaml、YOLO 权重（.pt / .onnx / .engine）不在 git 里。

cp ~/ros2/config/site.example.yaml ~/ros2/config/site.yaml
# 按新机器填写 robot.sn、robots[].ip、相机序列号、权重路径
# 权重放到 models/<分组>/ ，见 models/README.md

TensorRT 的 .engine 跟 GPU 绑定。换了显卡（哪怕仍是 3090 以外的型号）要在新机器的 ros_flexiv 里重新 bash ~/ros2/scripts/weights.sh convert --to engine。直接拷本机的 .engine 经常加载失败。

手眼结果 handeye/results/ 在 git 里，但是这台机器、这个相机安装位的矩阵。新机器克隆后要重新标定，见 HANDEYE.md。

在 ros_flexiv 里编真机（先确认 conda info --envs 里星号在 ros_flexiv，python 指向 ~/anaconda3/envs/ros_flexiv/bin/python）：

cd ~/ros2
conda activate ros_flexiv
bash scripts/build_all.sh
source scripts/env.sh
echo "ROS_DISTRO=$ROS_DISTRO ROS_DOMAIN_ID=$ROS_DOMAIN_ID"
# humble 与 0

编完查 shebang 没有被仿真环境污染（正常应是 0）：

grep -l ros_gz_sim install/*/lib/*/* | wc -l

仿真另开一个终端：

cd ~/ros2
bash scripts/build_sim.sh
source scripts/sim_env.sh
# 打印里应有 CONDA=ros_gz_sim  ROS_DISTRO=humble  ROS_DOMAIN_ID=77

---

9. 装完怎么确认

# 真机环境
source ~/ros2/scripts/env.sh
python -c 'import rclpy, torch, tensorrt, pyrealsense2, cv2, serial, minimalmodbus, onnx'
echo "$ROS_DISTRO $ROS_DOMAIN_ID"          # humble 0
~/rdk_py310/bin/python -c 'import flexivrdk; print(flexivrdk.__version__)'   # 1.9.1

# 仿真环境（新终端）
bash ~/ros2/scripts/install_sim_env.sh --verify

有机器人、示教器已切到 AUTO + Remote Ethernet、并且 config/site.yaml 已填好之后，再跑：

bash ~/ros2/scripts/test_rdk_python.sh
bash ~/ros2/scripts/run_real_preflight.sh --arm 89

这两条会访问真机网络，空机器上失败不代表环境没装上。

---

10. 本机还有、但本仓库不用的 conda 环境

conda env list 里还有 flexiv、flexiv_rdk_py312、orisys、py311、ros2。scripts/env.sh 和 scripts/sim_env.sh 都不会激活它们。新机器只建 ros_flexiv 和 ros_gz_sim 即可。