Files
a7l20-cup-grasp/docs/INSTALL.md
T

10 KiB
Raw Blame History

环境配置

系统与连接

  • Ubuntu 24.04 x86_64,Python 3.12 + venv;不使用 conda。
  • ROS 2 Jazzy;需要 rclpy、sensor_msgs、geometry_msgs、control_msgs、trajectory_msgs、shape_msgs、std_srvs、rosidl_runtime_py 和 moveit_msgs。几何模块复用消息类型,不要求启动 MoveIt Servo。
  • D405 使用 realsense2_camera,848×480、30 FPS、对齐深度;执行入口会复用或启动相机驱动。避免其他程序独占设备。
  • 下位机地址 192.168.10.21,原生 ROSBridge 端口 9090,机械臂保留厂家桥服务及反馈接口。
  • 左手 can0,1 Mbps,通过CAN返回的SN核对G20/LHT20型号和左手标识,不默认绑定单台设备SN。标定表随包提供;更换设备仍需确认角度标定,不能仅凭左右手相同直接套用。
  • ROS_DOMAIN_ID 默认 29。主机和下位机网络、USB/CAN 权限由现场配置。

先按 ROS 2 Jazzy 官方安装说明 配置 Ubuntu 24.04 的 ROS 软件源。已配置软件源的机器可补充系统组件:

sudo apt install python3.12-venv python3-pip iproute2 can-utils usbutils kmod libgl1 libglib2.0-0 \
  ros-jazzy-ros-base ros-jazzy-realsense2-camera ros-jazzy-rosbridge-server \
  ros-jazzy-control-msgs ros-jazzy-trajectory-msgs ros-jazzy-shape-msgs \
  ros-jazzy-moveit-msgs ros-jazzy-rosidl-runtime-py
bash scripts/setup.sh
bash run.sh check

requirements.txt 锁定原工作环境中实际使用的直接依赖版本。setup.sh 创建独立 .venv,并允许访问系统 ROS Python 包;不复制旧 venv。SDK 动态库随包保留在 runtime/arm/vendor,Linux x86_64 使用,其他架构需厂家对应库。

官方 SDK 与驱动来源

组件 来源与使用方式
A7 在线控制器 SDK 1.0.5 SDK 源码与下载入口,随包来源 commit 为 e1c4a4523a46e80e40c5dbe8cc651f2cf5fa4a51。原厂库、头文件及 SHA256 记录在 runtime/arm/vendor/lbot_sdk/provenance.json;无需再次下载相同平台的库。
RealSense SDK / Linux 驱动 librealsense、官方 Linux 安装说明。
RealSense ROS 2 驱动 realsense-ros 官方安装说明。本项目用 Jazzy 的 realsense2_camera。
Linux CAN 驱动层 内核 SocketCAN 文档。具体 USB-CAN 设备还需要匹配的内核驱动/固件。
CAN 命令行工具 linux-can/can-utils,Ubuntu 软件包为 can-utils。
Python CAN 接口 python-can SocketCAN 文档,requirements.txt 已固定 python-can==4.6.1。

机械臂通过以太网连接在线控制器;本流程的 can0 用于 G20 左手,不要求给机械臂安装直连 CAN SDK。pip 安装 python-can 不会安装 USB-CAN 内核驱动。ROSBridge 客户端 roslibpy 已在 requirements.txt 中;主机安装 rosbridge-server 不会替代下位机已有的厂家服务。

D405 相机驱动与检查

默认使用 ROS 软件源提供的 librealsense 和 ROS Wrapper,避免同时混装源码版与其他来源的库:

sudo apt update
sudo apt install 'ros-jazzy-librealsense2*' ros-jazzy-realsense2-camera
source /opt/ros/jazzy/setup.bash
ros2 pkg prefix realsense2_camera
lsusb
lsusb -t

将 D405 接到可靠的 USB 3 数据接口。相机 USB 权限需要 RealSense 的 udev 规则;安装后重新插拔相机。若设备识别、权限或内核兼容性仍有问题,按上方官方 Linux 指南核对当前内核支持范围和 udev 配置。采用厂家 Debian 驱动路线时,依指南配置厂家软件源并安装 librealsense2-dkms、librealsense2-utils、librealsense2-dev;这是替代安装路线,不应无条件叠加到已有源码/ROS SDK 安装之上。DKMS 与当前内核及 Secure Boot 配置需兼容。

厂家工具路线可用 rs-enumerate-devices 查看设备与支持的流配置,或用 realsense-viewer 看图;ROS 软件包路线不保证附带这两个工具。检查完关闭 Viewer 和直接 USB 采集程序,再启动 ROS 相机,避免争用同一 D405。默认抓取通过 ROS 获取图像,不需要另外 pip 安装 pyrealsense2。

仅检查相机时,可在独立终端启动与项目一致的配置:

source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=29
ros2 launch realsense2_camera rs_launch.py \
  camera_namespace:=camera camera_name:=camera \
  enable_color:=true enable_depth:=true \
  rgb_camera.color_profile:=848x480x30 \
  depth_module.depth_profile:=848x480x30 \
  align_depth.enable:=true

在另一终端检查(观察后 Ctrl-C 退出 hz):

source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=29
ros2 topic list
ros2 topic echo /camera/camera/color/camera_info --once --qos-reliability best_effort
ros2 topic hz /camera/camera/color/image_raw
ros2 topic hz /camera/camera/aligned_depth_to_color/image_raw

应能收到新的彩色图、对齐深度和有效相机内参,目标频率约 30 Hz;仅能列出话题不等于收到图像。主流程可以复用相同域/名称的驱动,不要重复启动。若报设备忙或 VIDIOC_S_FMT,先检查是否已有 ROS 相机、Viewer 或直连采集程序占用;不要用重新安装驱动代替占用排查。

G20 左手 CAN 驱动与检查

通信链路为:G20 → USB-CAN 适配器 → 对应内核驱动 → SocketCAN can0 → python-can → 本项目 G20 协议代码。适配器需支持 Linux SocketCAN、经典 CAN 和 1 Mbps;仓库不绑定某个 USB-CAN 型号,也不包含所有厂家驱动。

先识别设备和已有驱动:

sudo apt install iproute2 can-utils usbutils kmod
lsusb
ip -details link show type can
# 已有 can0 时查看实际绑定驱动;部分虚拟/串口接口无此路径
readlink -f /sys/class/net/can0/device/driver

若未出现 CAN 网络接口,应根据适配器型号、USB VID/PID 和厂家说明安装对应驱动,而不是反复运行 ip link:

  • gs_usb / candleLight 兼容设备使用内核 gs_usb 驱动;仅确认适配器兼容后运行 sudo modprobe gs_usb。
  • 串口 SLCAN 设备需按厂家串口协议、速率和固件配置 slcan/slcand;普通 USB 串口不自动等于 CAN 接口。
  • 专有 USB-CAN 设备按其厂家 Linux 文档安装,确认最终提供 SocketCAN 接口。仅有专有动态库、没有 SocketCAN 的设备不能直接替换本项目的 can0。
  • 若当前内核缺少所需模块,安装匹配当前内核的 Ubuntu 模块包或厂家驱动;不要将 gs_usb 当成所有设备的通用驱动。

设备空闲且接口已确认对应左手后,加载 CAN 协议模块并配置接口。若已在 1 Mbps 正常运行,仅检查即可,不要在控制期间 down/up:

sudo modprobe can
sudo modprobe can_raw
sudo ip link set dev can0 down
sudo ip link set dev can0 type can bitrate 1000000
sudo ip link set dev can0 up
ip -details -statistics link show dev can0

配置网络接口需要管理员权限;Python 抓取程序使用项目 venv,不以 sudo 代替环境安装。确认 CAN_H/CAN_L、参考地、独立供电和总线两端终端电阻符合设备说明;USB 接入不代表手本体已经供电。多适配器情况下先确认接口与设备对应关系,不能假定枚举出的 can0 一定是左手。

被动查看总线接收帧(不发送位置指令):

timeout 5s candump can0
ip -details -statistics link show dev can0
.venv/bin/python -c "import can; print(can.__version__)"

candump 等待到时退出属于正常现象;查询应答型设备在没有查询时可能完全无帧,因此空输出不能单独判故障,接口 UP 也不能证明设备有应答。检查 RX/TX、错误计数及 BUS-OFF 状态,再由项目既有身份/反馈预检确认实际左手。不要用随机 cansend/cangen 帧测试接有真机的总线。上述安装和接口检查不会替代设备身份、标定及执行前检查。

配置

需要覆盖解释器、ROS 环境或域号时,将 config/local.env.example 复制为 config/local.env 后编辑。文件已排除出 Git。直接运行 Python 模块前,先 source scripts/environment.sh,再 source 对应 ROS setup.bash。

config/camera_extrinsics_current.json 为共同 base_link 外参,右臂标定的指尖偏移不用于左手。视觉主线使用每轮新 RGB-D 与实测局部运动映射;默认杯子模式使用已保存的 HUG 形状模板,再优化当前几何,不要求现场运行大模型。

可选新物体 HUG 模式

--object-mode pointcloud 不是默认杯子流程。额外需要 HUG 源码、hug_full.safetensors 权重和其独立推理环境,以及 retarget_l20_v2.py 所在 retargeting 目录、dex-retargeting / pinocchio / PyYAML 环境。通过 HUG_ROOT、RETARGETING_ROOT、RETARGET_PYTHON 配置;权重和这些独立环境不包含在本仓库。本次不宣称此可选模式完成独立安装验收。

可选通用轨迹回放

默认杯子观察位路线不需要此组依赖。使用 runtime/arm 的通用 follow 轨迹规划时,先安装并编译离线 MoveIt TOTG 辅助程序:

sudo apt install g++ libeigen3-dev ros-jazzy-moveit-core ros-jazzy-ruckig
.venv/bin/python -m pip install -r requirements-replay.txt
.venv/bin/python runtime/arm/build_totg.py

源文件为 runtime/arm/cpp/totg_offline.cpp,输出 runtime/arm/build/totg_offline。构建与离线定时均不连接机器人;实际执行仍受原控制检查约束。CUP_ROS_PREFIX 可覆盖 ROS 安装目录,默认从 CUP_ROS_SETUP 推导。

手眼标定教程

独立项目:a7-handeye-calibration。按完整教程完成左右臂只读采点、求解和独立验证,再备份并替换本项目config/camera_extrinsics_current.json。默认抓取使用新RGB-D直接视觉伺服,不需要掌心Tag。