arm_dev
7942014763
验收：test_listed_arms 与 test_camera_preview 共 20 项通过。D435 1280×720 发布约 29 帧/秒。 Co-authored-by: Cursor <cursoragent@cursor.com>
318 lines
12 KiB
Markdown
318 lines
12 KiB
Markdown
# 环境安装（按本机快照复现）
|
||
|
||
本文是 **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. 新机器先对齐的路径
|
||
|
||
脚本跟**当前用户的家目录**走，不写死 `/home/cc`。用户名可以不是 `cc`。只支持 Linux。
|
||
|
||
| 路径 | 谁在用 |
|
||
|------|--------|
|
||
| `$HOME/anaconda3` 或 `$HOME/miniconda3` | `scripts/lib/dev_tools.sh`。环境名默认 `ros_flexiv`，可用 `REAL_ENV_NAME` 改 |
|
||
| `$HOME/rdk_py310/bin/python` | 默认的 RDK 解释器。已经在别的目录时，启动前 `export RDK_PYTHON=...` |
|
||
| `$HOME/flexiv_install` | `run_real.sh` / `env.sh` 的 `LD_LIBRARY_PATH` |
|
||
| 仓库目录 | 克隆到哪就从哪启动。`colcon build` 必须在 ASCII 路径下，不要在中文目录里编 |
|
||
|
||
机械臂、相机、夹爪、网卡和 IP 只写在 `config/site.yaml`。臂号是序列号末两位，换一台臂改 SN，不要改程序里的 89/91。工位窗口的显示器跟当前登录会话（`who` 里的 `:0` / `:1`），不写死某一块屏。
|
||
|
||
建议磁盘空闲 **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、路径填这个）。`$HOME/miniconda3` 也能被 `scripts/lib/dev_tools.sh` 找到。不要装到这两个目录以外的路径，除非自己改 `dev_source_conda`。
|
||
|
||
本机 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` 即可。
|