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

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

日常怎么用已经装好的环境，看 [QUICKSTART.md](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. 系统包与显卡

```bash
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。装完新开一个终端：

```bash
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 历史里。

```bash
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`。

```bash
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）：

```bash
# 源文件：~/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` 等包，**本仓库脚本不用它们**，新机器不必装。

激活后应看到：

```bash
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` 不是同一个版本。

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

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

拷完核对：

```bash
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）。

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

```bash
#!/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
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. 工作区、现场配置、编译

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

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

```bash
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](HANDEYE.md)。

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

```bash
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）：

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

仿真另开一个终端：

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

---

## 9. 装完怎么确认

```bash
# 真机环境
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
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` 即可。